Honcho 接入指南

一份"按这做就成"的指南。把 hermes 接入 Honcho cloud 的完整流程，含所有踩坑的预防方案。

配套：Honcho（实体）、Why Honcho over mem0（决策依据）、HERMES_HONCHO_RETRIEVAL_GUARDRAILS（铁律）。

总体步骤（约 30 分钟）

1. honcho.dev 注册 + 创建 workspace + 拿 admin scope key
2. 把 key 写到 .env + honcho.json
3. monkey patch SDK：屏蔽 delete_workspace（admin scope 唯一安全护栏）
4. 重启 hermes 容器
5. 验证：hermes honcho status 显示 Connection OK + 真业务调用 0 个 401

Step 1：注册 + 拿 admin scope key

1.1 注册 Honcho（5 分钟）

1. 浏览器：https://app.honcho.dev → GitHub OAuth 登录
2. 确认 dashboard 顶部"Free Credits Remaining" = $100
3. 进 Workspaces → + Create：
   • WORKSPACE ID: teamos-prod（或你的团队名）
   • METADATA: 可选 JSON（团队描述/owner 等，方便审计）
   • CONFIGURATION: {}（留空，让客户端按需配）
4. 创建好后能在列表看到 teamos-prod workspace ID

1.2 创建 admin scope API key（关键！）

进 API Keys 页面 → + Create：

字段	填什么	为什么
LABEL	ecs-hermes-<容器名>	多 key 时 dashboard 能区分 token 消耗
ADMIN ACCESS	Yes（一定要！）	Global / Workspace scope 实际等于纸面权限，干不了业务，详见 ../syntheses/Why Honcho over mem0#坑 4
SCOPE	Workspace（无所谓，反正会变 Global）	dashboard UI bug，现版本 v3 SCOPE=Workspace 实际保存 = Global
ID	teamos-prod	同上

生成的 key 形如 hch-v3-...，复制到密码管理器。dashboard 关闭后再也看不到完整 key。

每个 hermes 容器单独建一把 key（5 hermes = 5 key），不要共享：

• ✅ 审计粒度：dashboard 按 key 看 token 消耗
• ✅ 撤销影响小：丢 1 把只换 1 个容器

Step 2：写 .env + honcho.json

2.1 .env（仅传 API key）

# ECS: /opt/hermes-deploy/users/<user>.env
HONCHO_API_KEY=hch-v3-xxxxx

注：HONCHO_WORKSPACE_ID env 设了不被 SDK 读！必须用 honcho.json，详见 ../syntheses/Why Honcho over mem0#坑 2

2.2 /opt/data/honcho.json（关键配置）

每个容器内：

{
  "workspace": "teamos-prod",
  "apiKey": "hch-v3-xxxxx",
  "baseUrl": "https://api.honcho.dev",
  "environment": "production",
  "enabled": true,
  "hosts": {
    "hermes": {
      "enabled": true,
      "workspace": "teamos-prod",
      "aiPeer": "hermes-<容器名>",
      "peerName": "<真人名>",
      "apiKey": "hch-v3-xxxxx"
    }
  }
}

关键字段：

• workspace 和 hosts.hermes.workspace 都要写（root + host block 双保险）
• apiKey 在 root 和 host block 都写（同上）
• aiPeer = "hermes-<容器名>"（如 hermes-admin）—— assistant 维度的 peer 标识
• peerName = "<真人名>"（如 admin、jingwen）—— user 维度的 peer 标识

2.3 chmod 600（安全）

chmod 600 /opt/data/honcho.json
chmod 600 /opt/data/.env

Step 3：Monkey patch SDK（必做的 1 件事）

为什么要 patch：

• 屏蔽 delete_workspace — admin scope 能调它，一次调用清空整个 workspace 下所有 5 hermes 的 peer + session + message。LLM 工具误调、prompt injection、被盗 key 都可能触发。重命名方法让任何调用都 AttributeError，业务无影响。

演化历史：H 阶段（2026-04-17 切换初期）实际打了 2 个 patch：

1. ✅ delete_workspace disable —— 至今保留，安全 critical
2. ❌ _ensure_workspace skip —— Z 阶段（2026-04-18）撤回

当时是因为最早申请的是 Global scope key，SDK 启动时 POST /v3/workspaces 会 403，所以加 patch 跳过该调用。换成 admin scope key 后该调用能正常成功，patch 变成冗余优化（省一次网络往返），与上游 SDK 行为偏离反而增加未来调试成本，故撤回。

教训：先把 scope 调对，再考虑要不要为"非根因"加 patch。

3.1 patch 脚本（idempotent，多次跑无害）

/opt/hermes-deploy/honcho-patch.py：

"""Idempotent Honcho SDK monkey patch: disable delete_workspace."""
import os, sys

PATH = "/usr/local/lib/python3.11/site-packages/honcho/client.py"
if not os.path.exists(PATH):
    sys.exit(0)

content = open(PATH).read()
if "HERMES_PATCH_NO_DELETE_WORKSPACE" in content:
    print("[honcho-patch] already applied"); sys.exit(0)

needle = "    def delete_workspace(\n        self,\n        workspace_id: str = Field("
if needle not in content:
    print("[honcho-patch] ERROR needle not found"); sys.exit(1)

repl = (
    "    # HERMES_PATCH_NO_DELETE_WORKSPACE -- production safety: "
    "disabled to prevent admin-key disasters\n"
    "    def delete_workspace_DISABLED(\n"
    "        self,\n"
    "        workspace_id: str = Field("
)
open(PATH, "w").write(content.replace(needle, repl, 1))
print("[honcho-patch] applied")

应用到容器：

docker cp /opt/hermes-deploy/honcho-patch.py hermes-<user>:/tmp/honcho-patch.py
docker exec hermes-<user> python3 /tmp/honcho-patch.py

3.2 验证 patch 生效

# 检查 patch 标记存在（期望恰好 1 个）
docker exec hermes-<user> grep -c HERMES_PATCH /usr/local/lib/python3.11/site-packages/honcho/client.py
# 期望输出: 1

# 试调 delete_workspace 应该 AttributeError
docker exec hermes-<user> python3 -c "
import json
key = json.load(open('/opt/data/honcho.json'))['apiKey']
from honcho import Honcho
c = Honcho(api_key=key, workspace_id='teamos-prod')
try:
    c.delete_workspace('test')
    print('DANGER: delete callable!')
except AttributeError:
    print('SAFE: disabled')
"
# 期望输出: SAFE: disabled

3.3 Patch 跨容器重建持久化（重要）

Patch 改的是镜像内 site-packages/honcho/client.py —— docker restart 不丢，但 docker rm + run（deploy.sh 重新部署）或 docker pull 升级镜像会丢。

3 种持久化方案（建议用方案 A）：

方案	怎么做	优劣
A. deploy.sh 加 patch step	每次 deploy 自动跑 patch	✅ 推荐：一次配置，永久生效
B. 写自定义镜像	FROM hermes-official + RUN patch	重，要维护内部 registry
C. sitecustomize.py	放在 volume 里通过 PYTHONPATH 加载	跨升级不丢，但影响所有 python 进程

方案 A 实施：在 /opt/hermes-deploy/deploy.sh 容器 docker run 后加：

# 容器启动后 apply patch
docker cp /opt/hermes-deploy/honcho-patch.py hermes-${USER}:/tmp/honcho-patch.py
docker exec hermes-${USER} python3 /tmp/honcho-patch.py

当前状态（2026-04-18）：方案 A 还没落地，patch 是手工跑的。任何 docker pull 升级 hermes 镜像后必须立刻重新 patch，否则 delete_workspace 重新可调。计划在 post-honcho-cleanup-and-extension.plan.md Phase A5 落地此自动化。

Step 4：重启 hermes + 验证

docker restart hermes-<user>
sleep 12
docker exec hermes-<user> hermes honcho status

期望输出：

Honcho status
────────────────────────────────────────
  Host:           hermes
  Enabled:        True
  API key:        ...xxxx
  Workspace:      teamos-prod
  Config path:    /opt/data/honcho.json
  ...
  Connection... OK         ← 关键：必须 OK

Step 5：端到端业务验证

5.1 SDK 全流程测

docker exec hermes-<user> python3 -c "
import json
key = json.load(open('/opt/data/honcho.json'))['apiKey']
from honcho import Honcho
c = Honcho(api_key=key, workspace_id='teamos-prod')
user = c.peer('smoke-test-user')
ai = c.peer('smoke-test-ai')
s = c.session('smoke-test-session')
s.add_peers([user, ai])
s.add_messages([
    user.message('I love coffee with no sugar'),
    ai.message('Got it — no sugar')
])
import time; time.sleep(3)
print(user.chat('1 sentence about this user', reasoning_level='low'))
"

期望返回类似："This user enjoys coffee but prefers it without sugar."

5.2 业务日志检查

# 验证最近 1 小时无 401 / honcho 错误
docker logs hermes-<user> --since 1h | grep -iE "honcho|JWT|permissioned|401"

期望：空输出（没错误）。

5.3 dashboard 检查

浏览器打开 https://app.honcho.dev → workspace teamos-prod → Peers / Sessions：

• 应该能看到测试 peer 出现
• session 列表里有 hermes runtime 写的 session（默认叫 data 因为 cwd 是 /opt/data）

失败排查

症状	可能原因	解决
Connection... ERR	API key 错 / network	检查 key 前缀是 hch-v3-（无 E）
Connection OK 但业务 401	key 不是 admin scope	dashboard 重建 key 选 ADMIN ACCESS=Yes
JWT not permissioned for this resource	同上	同上
Invalid API key	key 复制错 / 已 revoke	检查 dashboard 上 key 还在不在
_ensure_workspace 401	API key 是 Global / Workspace scope 不是 admin	dashboard 重建 key 选 ADMIN ACCESS=Yes（不要再加 patch 跳过此调用，那是治标不治本，详见 Step 3 演化历史）
docker pull 升级后 delete_workspace 重新可调	patch 丢了	重跑 Step 3.1 patch 脚本（idempotent）或落地方案 A 自动化

安全清单（每月检查 1 次）

• [ ] dashboard 上 API key 列表没有未知 LABEL
• [ ] 月 token 消耗 < $30（5 hermes 全开估算）
• [ ] hermes 业务日志没有 honcho 401 错误
• [ ] patch 还在（grep -c HERMES_PATCH /usr/local/lib/python3.11/site-packages/honcho/client.py = 1）
• [ ] honcho.json 文件权限是 600
• [ ] 没人误把 .env 或 honcho.json 进 git

关联

• Honcho
• Honcho memory
• Why Honcho over mem0
• HERMES_HONCHO_RETRIEVAL_GUARDRAILS
• Hermes Agents